📖 [Docs]: Process-PSModule documentation is now organized by task - #448
Merged
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Introduced a new settings reference document detailing all available settings in `.github/PSModule.yml` with defaults. - Created a workflow inputs reference outlining the inputs, secrets, and permissions for the Process-PSModule reusable workflow. - Developed a design specification document explaining the architecture and workflow of Process-PSModule. - Established a specification document that outlines the requirements for the PowerShell module pipeline, including functional and non-functional requirements. - Added principles and practices documentation to guide versioning, branching, and development practices. - Removed outdated quickstart and workflow overview documents, consolidating information into new structured guides. - Updated navigation and references in the documentation to reflect the new structure and removed obsolete links. - Revised links to external coding standards to point to the updated MSX documentation.
Marius Storhaug (MariusStorhaug)
requested a review
from a team
as a code owner
August 9, 2026 08:11
Marius Storhaug (MariusStorhaug)
changed the title
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Process-PSModule documentation now leads with how to use the pipeline. Getting started, guides, reference, and specification are separate sections, so someone looking up a setting or wiring up their first module no longer has to read the specification and design first.
New: A guided path from template to first release
Getting started is now a walkthrough rather than a single page of bullets. It covers creating the repository from the template, configuring GitHub Pages and the PowerShell Gallery API key, adding the caller workflow and settings file, and then opening the first pull request and applying a version label. Bootstrapping a brand-new module with an integration branch sits alongside it.
New: Guides for the things people actually do
Seven task-oriented pages cover calling the workflow, configuring the pipeline with worked examples, structuring a module, writing module tests, skipping individual framework tests, versioning and releases, and validating a change before review. Writing module tests is new — test discovery rules, the
BeforeAll.ps1andAfterAll.ps1phases, and how to share expensive infrastructure across the platform matrix were previously buried inside the pipeline-stages page.Changed: Documentation is grouped by what you are trying to do
The section was a flat list of 15 sibling pages ordered specification, design, usage. It is now four ordered sections:
The specification and design are still published, just last, since few readers need them to use the pipeline.
Changed: Every fact has one home
The scenario matrix, the version-label mapping, the framework test IDs, the runtime settings contract, the repository setup steps, and the dependency list were each documented in two or three places. Each now lives on one page and is linked from the others, so they can no longer drift apart. The landing page also no longer prints the same page-index table twice.
Changed: Pointer-only pages are gone
The
PowerShell,Solutions, andStyle-Guidessections contained nothing but links to MSXOrg docs. They are removed and the pages that referenced them now link straight to the canonical MSX standards, removing a hop.Technical details
git mv, so file history follows the content.index.md+workflow-overview.md→ one landing page;module-anatomy.mdfolded intoguides/structuring-your-module.md; thebuild-test-pack-publish.mdstub replaced byguides/versioning-and-releases.md;usage.mdsplit intoguides/calling-the-workflow.md+reference/workflow-inputs.md;configuration.mdsplit intoguides/configuring-the-pipeline.md+reference/settings.md; test-authoring content extracted frompipeline-stages.mdintoguides/writing-module-tests.md.scenario-matrix.md,framework-test-ids.md,dependencies.md, plus aspecification/index.mdsection landing page.design.mddocumented.github/PSModule.ymlwithEnabled:keys while the real authorable contract usesSkip:. Rather than restate the contract, it now links toreference/settings.md, which removes the contradiction.design.mdalso carried its own copy of the runtimeSettingstable that had drifted from the one inpipeline-stages.md(Test.Module.Enabledvs the actualBeforeAllEnabled/MainEnabled/AfterAllEnabled). It now links to the pipeline-stages copy.docs/.github/linters/*set is removed in favour of the repository-level.github/linters/*, with the codespell, markdownlint, and PSScriptAnalyzer profiles updated to cover the docs corpus.docs/zensical.tomlnav rewritten to the four-section hierarchy.navigation.indexesis already enabled, so each section index is clickable and there are no dead nav nodes.docs/contentresolves; every in-tree heading anchor referenced by a link exists; everyzensical.tomlnav entry points at an existing file. This also clears two pre-existing broken links to../PowerShell/Standard/index.mdinModule-Types.mdandStandards.md..github/workflows/workflow.ymland the reusable sub-workflows are untouched; only the repository-internalDocs.ymland linter configs are modified, so there is no release impact for consumers.Relevant issues (or links)